SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_perl.idb/usr/freeware/catman/u_man/cat1/perlapio.Z/perlapio

Text File | 1998-10-28 | 15.7 KB | 397 lines

     PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))     22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))



     NNNNAAAAMMMMEEEE
      perlapio - perl's IO abstraction interface.

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          PerlIO *PerlIO_stdin(void);
          PerlIO *PerlIO_stdout(void);
          PerlIO *PerlIO_stderr(void);

          PerlIO *PerlIO_open(const    char *,const char *);
          int     PerlIO_close(PerlIO *);

          int     PerlIO_stdoutf(const char    *,...)
          int     PerlIO_puts(PerlIO *,const char *);
          int     PerlIO_putc(PerlIO *,int);
          int     PerlIO_write(PerlIO *,const void *,size_t);
          int     PerlIO_printf(PerlIO *, const char *,...);
          int     PerlIO_vprintf(PerlIO *, const char *, va_list);
          int     PerlIO_flush(PerlIO *);

          int     PerlIO_eof(PerlIO    *);
          int     PerlIO_error(PerlIO *);
          void    PerlIO_clearerr(PerlIO *);

          int     PerlIO_getc(PerlIO *);
          int     PerlIO_ungetc(PerlIO *,int);
          int     PerlIO_read(PerlIO *,void    *,size_t);

          int     PerlIO_fileno(PerlIO *);
          PerlIO *PerlIO_fdopen(int, const char *);
          PerlIO *PerlIO_importFILE(FILE *,    int flags);
          FILE   *PerlIO_exportFILE(PerlIO *, int flags);
          FILE   *PerlIO_findFILE(PerlIO *);
          void    PerlIO_releaseFILE(PerlIO    *,FILE *);

          void    PerlIO_setlinebuf(PerlIO *);

          long    PerlIO_tell(PerlIO *);
          int     PerlIO_seek(PerlIO *,off_t,int);
          int     PerlIO_getpos(PerlIO *,Fpos_t *)
          int     PerlIO_setpos(PerlIO *,Fpos_t *)
          void    PerlIO_rewind(PerlIO *);

          int     PerlIO_has_base(PerlIO *);
          int     PerlIO_has_cntptr(PerlIO *);
          int     PerlIO_fast_gets(PerlIO *);
          int     PerlIO_canset_cnt(PerlIO *);









     Page 1                        (printed 10/23/98)






     PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))     22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))



          char   *PerlIO_get_ptr(PerlIO *);
          int     PerlIO_get_cnt(PerlIO *);
          void    PerlIO_set_cnt(PerlIO *,int);
          void    PerlIO_set_ptrcnt(PerlIO *,char *,int);
          char   *PerlIO_get_base(PerlIO *);
          int     PerlIO_get_bufsiz(PerlIO *);


     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
      Perl's source    code should use    the above functions instead of
      those    defined    in ANSI    C's _s_t_d_i_o._h.  The perl headers will
      #define them to the I/O mechanism selected at    Configure
      time.

      The functions    are modeled on those in    _s_t_d_i_o._h, but parameter
      order    has been "tidied up a little".

      PPPPeeeerrrrllllIIIIOOOO ****
          This takes the place of FILE *. Like FILE    * it should be
          treated as opaque    (it is probably    safe to    assume it is a
          pointer to something).

      PPPPeeeerrrrllllIIIIOOOO____ssssttttddddiiiinnnn(((()))), PPPPeeeerrrrllllIIIIOOOO____ssssttttddddoooouuuutttt(((()))), PPPPeeeerrrrllllIIIIOOOO____ssssttttddddeeeerrrrrrrr(((())))
          Use these    rather than stdin, stdout, stderr. They    are
          written to look like "function calls" rather than
          variables    because    this makes it easier to    _m_a_k_e _t_h_e_m
          function calls if    platform cannot    export data to loaded
          modules, or if (say) different "threads" might have
          different    values.

      PPPPeeeerrrrllllIIIIOOOO____ooooppppeeeennnn((((ppppaaaatttthhhh,,,, mmmmooooddddeeee)))), PPPPeeeerrrrllllIIIIOOOO____ffffddddooooppppeeeennnn((((ffffdddd,,,,mmmmooooddddeeee))))
          These correspond to _f_o_p_e_n()/_f_d_o_p_e_n() arguments are the
          same.

      PPPPeeeerrrrllllIIIIOOOO____pppprrrriiiinnnnttttffff((((ffff,,,,ffffmmmmtttt,,,,............)))), PPPPeeeerrrrllllIIIIOOOO____vvvvpppprrrriiiinnnnttttffff((((ffff,,,,ffffmmmmtttt,,,,aaaa))))
          These are    _f_p_r_i_n_t_f()/_v_f_p_r_i_n_t_f() equivalents.

      PPPPeeeerrrrllllIIIIOOOO____ssssttttddddoooouuuuttttffff((((ffffmmmmtttt,,,,............))))
          This is _p_r_i_n_t_f() equivalent. printf is #defined to this
          function,    so it is (currently) legal to use
          printf(fmt,...) in perl sources.

      PPPPeeeerrrrllllIIIIOOOO____rrrreeeeaaaadddd((((ffff,,,,bbbbuuuuffff,,,,ccccoooouuuunnnntttt)))), PPPPeeeerrrrllllIIIIOOOO____wwwwrrrriiiitttteeee((((ffff,,,,bbbbuuuuffff,,,,ccccoooouuuunnnntttt))))
          These correspond to _f_r_e_a_d() and _f_w_r_i_t_e().    Note that
          arguments    are different, there is    only one "count" and
          order has    "file" first.

      PPPPeeeerrrrllllIIIIOOOO____cccclllloooosssseeee((((ffff))))

      PPPPeeeerrrrllllIIIIOOOO____ppppuuuuttttssss((((ffff,,,,ssss)))), PPPPeeeerrrrllllIIIIOOOO____ppppuuuuttttcccc((((ffff,,,,cccc))))
          These correspond to _f_p_u_t_s() and _f_p_u_t_c().    Note that
          arguments    have been revised to have "file" first.



     Page 2                        (printed 10/23/98)






     PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))     22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))



      PPPPeeeerrrrllllIIIIOOOO____uuuunnnnggggeeeettttcccc((((ffff,,,,cccc))))
          This corresponds to _u_n_g_e_t_c().  Note that arguments have
          been revised to have "file" first.

      PPPPeeeerrrrllllIIIIOOOO____ggggeeeettttcccc((((ffff))))
          This corresponds to _g_e_t_c().

      PPPPeeeerrrrllllIIIIOOOO____eeeeooooffff((((ffff))))
          This corresponds to _f_e_o_f().

      PPPPeeeerrrrllllIIIIOOOO____eeeerrrrrrrroooorrrr((((ffff))))
          This corresponds to _f_e_r_r_o_r().

      PPPPeeeerrrrllllIIIIOOOO____ffffiiiilllleeeennnnoooo((((ffff))))
          This corresponds to _f_i_l_e_n_o(), note that on some
          platforms, the meaning of    "fileno" may not match Unix.

      PPPPeeeerrrrllllIIIIOOOO____cccclllleeeeaaaarrrreeeerrrrrrrr((((ffff))))
          This corresponds to _c_l_e_a_r_e_r_r(), i.e., clears 'eof' and
          'error' flags for    the "stream".

      PPPPeeeerrrrllllIIIIOOOO____fffflllluuuusssshhhh((((ffff))))
          This corresponds to _f_f_l_u_s_h().

      PPPPeeeerrrrllllIIIIOOOO____tttteeeellllllll((((ffff))))
          This corresponds to _f_t_e_l_l().

      PPPPeeeerrrrllllIIIIOOOO____sssseeeeeeeekkkk((((ffff,,,,oooo,,,,wwww))))
          This corresponds to _f_s_e_e_k().

      PPPPeeeerrrrllllIIIIOOOO____ggggeeeettttppppoooossss((((ffff,,,,pppp)))), PPPPeeeerrrrllllIIIIOOOO____sssseeeettttppppoooossss((((ffff,,,,pppp))))
          These correspond to _f_g_e_t_p_o_s() and    _f_s_e_t_p_o_s(). If platform
          does not have the    stdio calls then they are implemented
          in terms of _P_e_r_l_I_O__t_e_l_l()    and _P_e_r_l_I_O__s_e_e_k().

      PPPPeeeerrrrllllIIIIOOOO____rrrreeeewwwwiiiinnnndddd((((ffff))))
          This corresponds to _r_e_w_i_n_d(). Note may be    redefined in
          terms of _P_e_r_l_I_O__s_e_e_k() at    some point.

      PPPPeeeerrrrllllIIIIOOOO____ttttmmmmppppffffiiiilllleeee(((())))
          This corresponds to _t_m_p_f_i_l_e(), i.e., returns an
          anonymous    PerlIO which will automatically    be deleted
          when closed.

      CCCCoooo----eeeexxxxiiiisssstttteeeennnncccceeee wwwwiiiitttthhhh ssssttttddddiiiioooo

      There    is outline support for co-existence of PerlIO with
      stdio.  Obviously if PerlIO is implemented in    terms of stdio
      there    is no problem. However if perlio is implemented    on top
      of (say) sfio    then mechanisms    must exist to create a FILE *
      which    can be passed to library code which is going to    use
      stdio    calls.



     Page 3                        (printed 10/23/98)






     PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))     22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))



      PPPPeeeerrrrllllIIIIOOOO____iiiimmmmppppoooorrrrttttFFFFIIIILLLLEEEE((((ffff,,,,ffffllllaaaaggggssss))))
          Used to get a PerlIO * from a FILE *.  May need
          additional arguments, interface under review.

      PPPPeeeerrrrllllIIIIOOOO____eeeexxxxppppoooorrrrttttFFFFIIIILLLLEEEE((((ffff,,,,ffffllllaaaaggggssss))))
          Given an PerlIO *    return a 'native' FILE * suitable for
          passing to code expecting    to be compiled and linked with
          ANSI C _s_t_d_i_o._h.

          The fact that such a FILE    * has been 'exported' is
          recorded,    and may    affect future PerlIO operations    on the
          original PerlIO *.

      PPPPeeeerrrrllllIIIIOOOO____ffffiiiinnnnddddFFFFIIIILLLLEEEE((((ffff))))
          Returns previously 'exported' FILE * (if any).  Place
          holder until interface is    fully defined.

      PPPPeeeerrrrllllIIIIOOOO____rrrreeeelllleeeeaaaasssseeeeFFFFIIIILLLLEEEE((((pppp,,,,ffff))))
          Calling PerlIO_releaseFILE informs PerlIO    that all use
          of FILE *    is complete. It    is removed from    list of
          'exported' FILE *s, and associated PerlIO    * should
          revert to    original behaviour.

      PPPPeeeerrrrllllIIIIOOOO____sssseeeettttlllliiiinnnneeeebbbbuuuuffff((((ffff))))
          This corresponds to _s_e_t_l_i_n_e_b_u_f().    Use is deprecated
          pending further discussion. (Perl    core uses it _o_n_l_y when
          "dumping"; it has    nothing    to do with $| auto-flush.)

      In addition to user API above    there is an "implementation"
      interface which allows perl to get at    internals of PerlIO.
      The following    calls correspond to the    various    FILE_xxx
      macros determined by Configure. This section is really of
      interest to only those concerned with    detailed perl-core
      behaviour or implementing a PerlIO mapping.

      PPPPeeeerrrrllllIIIIOOOO____hhhhaaaassss____ccccnnnnttttppppttttrrrr((((ffff))))
          Implementation can return    pointer    to current position in
          the "buffer" and a count of bytes    available in the
          buffer.

      PPPPeeeerrrrllllIIIIOOOO____ggggeeeetttt____ppppttttrrrr((((ffff))))
          Return pointer to    next readable byte in buffer.

      PPPPeeeerrrrllllIIIIOOOO____ggggeeeetttt____ccccnnnntttt((((ffff))))
          Return count of readable bytes in    the buffer.

      PPPPeeeerrrrllllIIIIOOOO____ccccaaaannnnsssseeeetttt____ccccnnnntttt((((ffff))))
          Implementation can adjust    its idea of number of bytes in
          the buffer.

      PPPPeeeerrrrllllIIIIOOOO____ffffaaaasssstttt____ggggeeeettttssss((((ffff))))
          Implementation has all the interfaces required to    allow



     Page 4                        (printed 10/23/98)






     PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))     22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))



          perl's fast code to handle <FILE>    mechanism.

        PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
                      PerlIO_canset_cnt(f) && \
                      `Can set pointer into buffer'


      PPPPeeeerrrrllllIIIIOOOO____sssseeeetttt____ppppttttrrrrccccnnnntttt((((ffff,,,,pppp,,,,cccc))))
          Set pointer into buffer, and a count of bytes still in
          the buffer. Should be used only to set pointer to    within
          range implied by previous    calls to PerlIO_get_ptr    and
          PerlIO_get_cnt.

      PPPPeeeerrrrllllIIIIOOOO____sssseeeetttt____ccccnnnntttt((((ffff,,,,cccc))))
          Obscure -    set count of bytes in the buffer. Deprecated.
          Currently    used in    only doio.c to force count < -1    to -1.
          Perhaps should be    PerlIO_set_empty or similar.  This
          call may actually    do nothing if "count" is deduced from
          pointer and a "limit".

      PPPPeeeerrrrllllIIIIOOOO____hhhhaaaassss____bbbbaaaasssseeee((((ffff))))
          Implementation has a buffer, and can return pointer to
          whole buffer and its size. Used by perl for ----TTTT / ----BBBB
          tests.  Other uses would be very obscure...

      PPPPeeeerrrrllllIIIIOOOO____ggggeeeetttt____bbbbaaaasssseeee((((ffff))))
          Return _s_t_a_r_t of buffer.

      PPPPeeeerrrrllllIIIIOOOO____ggggeeeetttt____bbbbuuuuffffssssiiiizzzz((((ffff))))
          Return _t_o_t_a_l _s_i_z_e    of buffer.

























     Page 5                        (printed 10/23/98)






     PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))     22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))       PPPPEEEERRRRLLLLAAAAPPPPIIIIOOOO((((1111))))























































     Page 6                        (printed 10/23/98)